MACD 5

home *** CD-ROM | disk | FTP | other *** search

/ MACD 5 / MACD 5.bin / workbench / tools / czesc_3 / multirename / multirename.doc < prev next >

Wrap

Text File | 1994-12-08 | 33KB | 891 lines

MultiRename v1.0 Author: Daniel S. Milling Jr. Copyright © 1994 Daniel S. Milling Jr. All Rights Reserved ---------------------------------------------------------------------------- DISCLAIMER The author makes no warranties or representations, either expressed or implied, with respect to the program and information included herein. The product presented herein is being supplied on an "as is" basis and is expressly subject to change without notice. YOU USE THIS PROGRAM AT YOUR OWN RISK. In no event will the author be held liable for direct, indirect, incidental, or consequential damages resulting from the use or misuse of the program and information provided herein. DISTRIBUTION MultiRename is Shareware. The MultiRename program and all included files are Copyright © 1994 Daniel S. Milling Jr. All Rights Reserved. MultiRename is freely redistributable in it's original form to any bulletin board, public domain software collection, or network system as long as the original archive is kept intact in it's entirety and remains unaltered and as long as no fee, other than nominal media cost, is charged for distribution. This program, in whole or in part, may not be included in any commercial package without the prior written consent of the author. SHAREWARE FEE This version and all future versions of MultiRename will be released as FULLY functional programs, not crippled in any way. The reason for this is so that everyone who uses this program will have the complete working version, and will be able to judge for themselves whether MultiRename is a program which will be of use to them. If, after a trial period of 30 days, you find that this program is of use to you, you should send in the $10 shareware registration fee to: Daniel S. Milling Jr. 2125 N. Lilly Rd Elm Grove WI 53122 INTRODUCTION This program was spawned from the need to renumber and/or rename files which shared the same base name with numerical extensions. Files generated with many graphics packages have names which consist of a base name with a numerical value either prefixed or postfixed. The purpose of MultiRename is to allow the user to rename or renumber up to 1 million files with a common base name. Features: --------- - Ability to rename up to 1,000,000 files which contain a common base filename and a prefixed or postfixed numerical extension. - Ability to renumber files with offset values ranging from -999999 to +999999. - Ability to change the numbering style. There are four supported numbering conventions. These are: <FILENAME>.EXTENSION, <FILENAME>EXTENSION, EXTENSION.<FILENAME> and EXTENSION<FILENAME>. You may postfix or prefix a file with a numerical extension either separated with a '.' or with no separator at all. - Ability to change the number of digits for the numerical extension. If the user wanted to change files from, for example, the <filename>.xxxx format to the format used by Video Toaster framestore files of xxx.<FS.filename>, it is quick and easy to do. - Ability to select a range of filenames to either rename or renumber. - Rename or renumber files to the same directory or to a different directory or device. - Two supported renaming methods. Rename files either with or without a temporary directory. Depending on the situation, use of a temporary directory will speed up file operations to the same directory when a large amount of files are present. - Three supported methods of filename examination. - Optional Logfile which will record every operation done for each file. - Percent Scroller constantly updating the progress of the operation. - Current file readout telling what file is being operated on. - Works very well with disk caching programs. Requirements ------------ - Kickstart 2.x or above. - asl.library version 37 or above (38 or above is HIGHLY preferred) If you don't have the asl.library the program is still usable although you won't get a file requester. INSTALLATION To install MultiRename, just move the MultiRename program icon into the desired drawer through Workbench. You may now run it by double clicking on the program icon. From CLI just type in the program name when you are in it's directory or include the full path if you're not. HOW TO USE THE PROGRAM After you click on the program icon you are presented with the MultiRename screen. There are four sections to the program. From top to bottom, these are the FILE AREA, BASE FILENAME AREA, RENAME PARAMETERS and the OUTPUT AREA. Each portion will be explained individually. FILE AREA The FILE AREA section allows the user to either select a file via file requester or by entering the filename directly into the string gadget. There are three gadgets in this section which handle the source, destination and new file names. SOURCE FILE BUTTON ------------------ When you select this button, you will bring up the asl file requester which will allow you to select any filename as described in the below SOURCE FILE STRING GADGET description. If you do not have the asl.library, you will be presented with a warning instead. You may still use the string input however. SOURCE FILE STRING GADGET ------------------------- When you click this gadget you may enter the complete path including the name of any file in the series of files you wish to rename or renumber. You may enter the name of ANY file with ANY numerical extension. If you have selected a file with either a numerical prefix or postfix, the computer's interpretation of the filename will be printed below in the BASE FILENAME AREA and the Destination Directory will be set to this Source directory. If the file is not recognized or does not contain valid numerical data, you will receive an error message in the OUTPUT AREA detailing the problem. For example, if you have 100 files with a base filename of 'animation' numbered from 1 to 100, you may select ANY one of these filenames to use as a reference to that list of filenames. If you picked the file named 'animation.34' all files with the 'animation' base name will be affected by the operation relative to the variables you set in the RENAME PARAMETERS section. Details will be given in that section. By default, all files are affected. DESTINATION FILE BUTTON ----------------------- When this gadget is clicked the asl file requester will appear, allowing the user to select the destination directory. The destination directory is automatically set to the source directory once the source has been defined. The destination may be the same directory or a different directory on the same device or another device. DESTINATION STRING GADGET ------------------------- Allows the user to directly type in the name of the destination directory. NEW FILENAME STRING GADGET -------------------------- The new name for the series of files to be renamed is entered in this field. This file name may be the same as the original name. There are a few rules which must be followed when a new name is entered. These are: - The new name cannot contain illegal characters such as; '/', ':', '"', etc. Uppercase and lowercase characters are allowed as are legal punctuation characters. - The first or the last character cannot be a numerical character. If this was allowed, the new filenames would be misnumbered in a few cases. - New filenames may be as long as 23 characters. The prefix or postfix extensions, under the control of the program, may be as long as an additional 7 characters. After the user enters a name, a message will appear notifying the user that a valid name has been entered or that an error has occurred. NOTES ----- There are some filenames which may pose a problem with MultiRename. These filenames contain numerical values at the beginning AND the end of the filename. Sometimes this will cause the program to misinterpret the actual numbering method. You may change the way MultiRename examines the filename. This is done by changing the EXAMINATION METHOD by clicking on it's cycle gadget which is found in the RENAME PARAMETERS section. Details may be found in that section of the documentation. The default examination method will first check to see if there is a number at the end of the filename. If that fails then it will check the beginning of the filename. BASE FILENAME AREA The BASE FILENAME AREA shows the user how the computer has interpreted the inputted filename. There are three output boxes in this section. BASE FILENAME ------------- This is what the computer thinks the base filename is, minus the prefix or postfix numerical data. If a filename contained a '.' numerical separator, it will also be included in the base filename. This is normal. ONLY FILES WHICH MATCH THIS BASE FILENAME WILL BE PROCESSED. PREFIX ------ If the computer determines that the filename contains a numerical prefix, that prefix will be shown in this output box. There may only be a prefix OR a postfix value shown. You will never see both shown at the same time. POSTFIX ------- If the computer determines that the filename contains a numerical postfix, that postfix will be shown in this output box. There may only be a prefix OR a postfix value shown. You will never see both shown at the same time. NOTES ----- There are some filenames which may pose a problem with MultiRename. These filenames contain numerical values at the beginning AND the end of the filename. Sometimes this will cause the program to misinterpret the actual numbering method. You may change the way MultiRename examines the filename. This is done by changing the EXAMINATION METHOD by clicking on it's cycle gadget which is found in the RENAME PARAMETERS section. Details may be found in that section of the documentation. The default examination method will first check to see if there is a number at the end of the filename. If that fails then it will check the beginning of the filename. RENAME PARAMETERS AREA The RENAME PARAMETERS AREA is where the user may change the renaming and numbering parameters. The user may select a range of files to renumber, select a renumbering offset, change the renumbering method, change the filename examination method, change the renaming method and more. HIGH NUMBER ----------- This string gadget allows the user to enter the maximum numerical extension a file may have and still be processed. For example, if the High Number is set to 1000 and you have a file with the extension '<filename>.1001' that file will not be processed. There are a few rules which must be followed when setting the High Number. These are: - The High Number may not be greater than 9, 99, 999, 9999, 99999 or 999999 depending on the number of digits currently selected with the Digits Slider. - The High Number may not be negative or less than the low number. - The High Number + Offset Value may not be greater than 9, 99, 999, 9999, 99999 or 999999, again depending on the number of digits selected with the Digits Slider. - The High Number will always be at the maximum allowable value upon startup, upon the selection of the RESET button or after changing the Digits Slider value. - The High Number will also be scaled according to the current Offset value. For example, if the current High Number is 9999 and a value of 100 is entered into the Offset String Gadget, the High Number will be scaled down to 9899 to accomodate the renumbering offset of +100. After the user enters a number, a message will appear either notifying the user that a valid number was entered or that an error has occurred. LOW NUMBER ---------- This gadget allows the user to enter the lowest numerical extension a file may have and still be processed. For example, if the Low Number is set to 25 and there is a file with the extension '<filename>.24' that file will not be processed. There are a few rules which must be followed when setting the Low Number. These are: - The Low Number may not be less than 0. The default value is 0. - The Low Number may not be greater than the High Number. - The Low Number + Offset value may not be less than 0. - If the sum of the Low Number + Offset Number is less than 0, then the Low Number will be scaled according to the value of the Offset Number. For example, if a Low Number of 10 was entered and an Offset Number of -15 was then entered, the Offset number of -15 is valid but the Low Number will be scaled up to +15 to accomodate this Offset value. - If a low number is entered which is illegal after a legal offset value was enter, the Offset Number will be zeroed and an error message will be given. The user may now enter a new Offset value. After the user enters a number, a message will appear either notifying the user that a valid number was entered or that an error has occurred. OFFSET NUMBER ------------- This gadget allows the user to enter a positive or negative value which will be used to recompute the file extension number of each file. For example, if the Low value is 10 and the Offset value is -5, all files, which match the base filename parameters, will be renumbered in such a way where x is equal to the old numerical extension and x-5 is equal to the new numerical extension. There are a few rules which must be followed when setting the Offset Number. These are: - The Offset Number may be positive or negative. The default value is zero. - The Offset Number may not be greater than the maximum High Number according to the currently selected number of digits, represented by the Digits Slider. - The Low Number + Offset Number may not be less than zero. If a Low number of 0 was entered and an Offset Number of -10 was then entered, the Low Number would be scaled up to +10 in order to accomodate the new Offset Number. - If a Low Number is entered which conflicts with an Offset Number, then an error message will be given and the Offset Number will be set to zero. - The Offset Number may not be less than (-1 * Maximum High Number.) After the user enters a number, a message will appear either notifying the user that a valid number was entered or that an error has occurred. IMPORTANT NOTE! When setting the Offset Number to anything other than zero, if the Low and/or High Number has been changed, this may cause a conflict if the operation is to be performed on the same directory. Try setting the Destination to a different directory or device and it will work unless a file already exists with that name. Also using a different New Filename will solve the problem as well. For example, if there is a series of files, numbered from 10 to 100, with a Low value of '20', High value of '50' and offset value of '-5' there will be a problem when file '20' is renumbered as file '15' since file '15' already exists. If the New Filename is something other than the original filename, then this problem will not occur. RESET BUTTON ------------ The Reset Button, when clicked, will reset the High, Low and Offset values to their defaults. High will be set to the maximum allowable, determined by the Digits Slider gadget; 9, 99, 999, 9999, 99999 or 999999. Low and Offset will both be set to zero. NUMBERING METHOD ---------------- There are two different types of numbering methods for the New filename. These are: - PREFIX: This will add the numerical value to the beginning of the filename. - POSTFIX: This will add the numerical value to the end of the filename. This is the Default value. You may change the numbering method of any series of files between any of the selectable modes at any time. EXAMINATION METHOD ------------------ This allows the user to change the method by which a filename is examined. Because some filenames have numerical data at the beginning and the end, the program may misinterpret the actual file extension number. Changing the examination method will fix this possible problem. There are three possible examination methods. These are: - PREFIX ONLY. The program will only look at the beginning of the selected filename for a numerical extension. If none is found, an error message will appear. Otherwise the user may proceed. - POSTFIX ONLY. The program will only look at the end of the selected filename for a numerical extension. If none is found, an error message will appear. Otherwise the user may proceed. - DEFAULT. The program will first look at the end of the filename. If no numerical extension is found, the program will proceed to look at the beginning of the filename. If no numerical extension is found an error message will appear. Otherwise the user may proceed. The user may see if the filename and extension are proper by looking at the BASE FILENAME area. The Base Filename and Prefix or Postfix number will be printed out. If the output is not satisfactory, changing the Examination Method may alleviate the problem. After the Examination Method is changed a message will be printed telling whether an error has occurred. RENAMING METHOD --------------- There are two methods of renaming. These are Default and No Temp Dir. - DEFAULT: The program will Automatically decide when a temporary directory is needed. A temp directory is used only when files are being renamed to the same directory. This is not a necessity, but mainly a speed consideration. It was found that if a temporary directory structure was produced to which the renamed files are moved and then moved back to the original directory, the operation was MUCH faster then just renaming to the same directory. There is one exception to this rule: Directory caching programs. Disable temporary directories with disk caching programs. Temporary directories with disk caching will only slow down the process. - NO TEMP DIR: This will disable temporary directory creation. Use this setting when using directory caching programs. IMPORTANT NOTE! Never disable temporary directory creation when the New Filename is the same as the original filename. This could cause problems. The program will detect this conflict and refuse to continue with the operation and abort. SEPARATOR --------- This will determine if a '.' will be placed between the file name and it's numerical extension if one does not already exist. The two choices are: -(None): No period will be added to the new filename. -'.' (Period): A period will be added to the new filename. DIGITS SLIDER GADGET -------------------- This will determine how many digits the extension of the new file name will have. You may have as few as 1 and as many as 6 digits. You may also change the number of digits a file name extension has. For example of you have files numbered from 001 to 545, you may renumber these so that the new extensions would be from 000001 to 000545. These digits may be renumbered like this as many times as you would like. There is only one problem with this. Taking the above example, if we were to renumber files 001 to 545 using only two digits for the numerical extension, only files 001 to 099 will be affected since by changing the Digits Slider setting, the High Number is automatically scaled to the Maximum number of X digits which may be included. The value X may be 9, 99, 999, 9999, 99999 or 999999 for 1 to 6 digits respectively. LOGFILE CYCLE GADGET -------------------- This gadget will determine if a logfile is to be created. This logfile will record every action performed on each file. This includes showing the source and destination directories and where an error may have occured. The logfile name is in the form of 'MultiRenameX.logfile' where 'X' is a number from 1 on up. The first logfile to be created will be 'MultiRename1.logfile' while the second is 'MultiRename2.logfile' etc. If a logfile already exists, the new file will be bumped up to the next free number. The default is no logfile. LOGFILE PATH BUTTON ------------------- This button will allow the user to change the default path to which the logfile will be saved to. The default path is RAM:. IMPORTANT NOTE! If the path is changed to the same device which the renaming operation is taking place, logfile creation may slow down the process of renaming files. PROCESS BUTTON -------------- When this button is clicked, the program will proceed with the renaming/renumbering of files. If all requested data is valid, the program will go ahead and process the files. If there is any invalid data an appropriate error message will be reported. If the destination directory already contains files, even if the source is the same as the destination, the program will compare the list of new file names it has built to the existing files in the destination directory. If there is a conflict, the program will notify the user and halt. If there is no conflict the program will ask the user if he or she would like to proceed with the rename process. Once the process starts it must be carried out to completion. OUTPUT AREA This is the area where all messages are printed along with the name of the file currently being operated upon. CURRENT FILE ------------ This text box will tell the user what file is currently being manipulated. If an error should occur, this text box will contain the name of the file which the error occured upon. MESSAGE AREA ------------ The message area will display any messages which confirm an action or occurrence of an error. PERCENT COMPLETE SCROLLER When a complex operation is about to be performed, a small window will open containing the Percent Complete readout. This is the status bar which will notify the user of what percentage of data has been processed. KEYBOARD EQUIVALENTS This is a listing of all keyboard commands. a - Toggle Separator d - Destination File Selection e - Examination Method f - New Filename g - Logfile toggle h - High Number i - Digits Slider l - Low Number m - Renaming Method n - Numbering Method o - Offset number p - Process button r - Reset s - Source File Selection t - Logfile path selection MENUS Under the project menu there are four selections. The selections, followed by their Right Amiga key combination, are: OPEN (RA-O)- Does the same thing as hitting the Source File button. SAVE AS (RA-S)- Does the same thing as hitting the Destination Directory button. ABOUT (RA-A)- Gives some information about the program and author. QUIT (RA-Q)- ends the program. ERROR MESSAGES There are a number of error messages which may appear during the course of running the program. What follows is an explanation of each message. FILENAME BUFFER OVERFLOW The entered path name is longer than 990 characters which is the maximum allowable number of characters which the program may handle for a path. This should be enough. NEW FILENAME MISSING No name was entered in the New Filename string and the user hit <RETURN>. NUMBER AT BEGINNING OR END OF FILENAME There may not be a numerical character as the first or last character of the New Filename. ILLEGAL CHARACTERS IN FILENAME An illegal character such as '/', ':' or '"' was found in the New Filename. THE SUM OF (LOW+OFFSET) MAY NOT BE LESS THAN ZERO The sum of Low + Offset was less than zero. THE SUM OF (HIGH+OFFSET) MAY NOT BE > x The sum of High + Offset may not be greater than the maximum allowable value, x. LOW FRAME CANNOT BE GREATER THAN HIGH When in Low Input, a number was entered which was greater than the High value. LOW FRAME CANNOT BE NEGATIVE OR ZERO When in Low Input, a number was entered which was zero or negative. HIGH FRAME MAY NOT EXCEED x When in High Input, a number was entered which exceeds the maximum allowable value of x. HIGH FRAME CANNOT BE LESS THAN LOW When in High Input, an invalid number was entered which was less then the Low value. OFFSET MUST BE BETWEEN x AND y When in Offset Input, an invalid number was entered which was not between the allowable values of x to y. INVALID FILENAME The PROCESS button was clicked before a valid filename was entered either by the FILENAME button or the FILENAME input string. YOU MUST ENTER A NEW FILE NAME The PROCESS button was clicked before a valid New Filename was entered. NO FILES FIT GIVEN PARAMETERS After clicking the PROCESS button, no files could be matched with the Base Filename. No further action is taken by the program. MISSING FILE NAME If a valid directory path was entered, but no filename was given, this error message prompts the user to enter the complete path with filename. CANNOT FIND FILE The filename which was inputted could not be found. The user is prompted to enter a new filename. FILENAME CONTAINS NO NUMERICAL DATA No numerical data could be found for the current entered filename relative to the current Examination Method. Changing the Examination Method may help. POSTFIX MUST BE 6 CHARACTERS OR LESS The selected file has a postfix of seven numerical characters or more. The maximum number of numerical postfix digits is six. PREFIX MUST BE 6 CHARACTERS OR LESS The selected file has a prefix of seven numerical characters or more. The maximum number of numerical prefix digits is six. FILENAME MUST CONTAIN CHARACTER DATA The selected filename cannot just be a string of numbers. At least one non-numerical character must be present in the name. ERROR DURING RENAME. OPERATION HALTED An error has occurred while the rename operation was processing. The most common errors are when a file already exists or a file could not be found. This usually occurs during a renumbering operation when the New filename is the same as the old filename. MEMORY ALLOCATION FAILED The program couldn't get enough memory for the file copying buffer. You need 64k free in order to allocate this buffer. COULD NOT SUCCESSFULLY OPEN FILE During a file copying procedure, the original file was unable to be opened. Either the file has been moved or another program has an exclusive lock on this file. COULD NOT SUCCESSFULLY EXAMINE FILE During a file copying procedure, the original file could be opened but not examined. COULD NOT SUCCESSFULLY OPEN NEW FILE A new file could not be created during a copying procedure. The destination directory may be full. COULD NOT SUCCESSFULLY EXAMINE NEW FILE A new file was successfully created during a copying procedure but it could not be examined. SHORT FILE READ During a copying procedure, part of the original file was not able to be read. This could be caused by the original file being corrupt. COULD NOT SUCCESSFULLY WRITE NEW FILE During a copying procedure, data could not be written to the output file. DUPLICATE FILE EXTENSION FOUND Two files with the same file number were found. An example would be 'filename.0010' and 'filename.010' Since the program is dealing with true numbers, not numbers padded with zeros, it sees these two files as having the identical numerical extension. INVALID LOGFILE DIRECTORY ENTERED An invalid or non-existent directory was selected for the logfile path. INVALID DESTINATION DIRECTORY ENTERED An invalid or non-existent directory was selected for the destination path. COULD NOT OVERRIDE FILE PROTECTION. A protected file was found and it's protection could not be overriden. Perhaps the file is locked by another program. CREATION OF MAIN TEMPORARY DIRECTORY FAILED The main temporary directory could not be created. Perhaps the volume is full or protected. CREATION OF TEMPORARY SUB-DIRECTORY FAILED The sub-directory structure could not be created. Perhaps the volume is full or protected FILE COULD NOT BE COPIED The file could not be copied possibly due to the volume being full or a lock has been put on the source file. ORIGINAL FILE COULD NOT BE REMOVED The file couldn't be removed possibly due to another program having a lock placed upon it or it is corrupt. PRECAUTIONS There are a few precautions the user must take into account when using this program. After clicking the PROCESS button, the program will do a number of comparisons and if everything is in order a requester will appear asking if the user would like to continue with the rename process. If the user elects to continue, the operation may not be aborted after this point. The operation will only halt when it naturally finishes or an error has occurred. DO NOT reset or turn off the computer until the rename operation has finished. If the computer is reset, powered down or crashes during this rename operation, there is a risk of causing a disk error and the possibility of data loss. This program is fully multitasking, but it is recommended that no other disk accesses are performed on the drive where the rename operation is occurring. Although, the MultiRename program does not crash when multiple accesses are performed on the drive during a rename operation, it would be a wise precaution to avoid multiple accesses. It would be wise to avoid running programs in the background which may cause a system crash. If a system crash were to occur during a rename function, there is the possibility of data corruption and/or loss. This program has been tested hundreds of times and used in a productive manner dozens of times with no loss of data or corruption of files. If you find that an error has occurred and the operation was halted (see error section) it would be relevant to note that no files have been lost. All files after and including the file which caused the error will not have been renamed or renumbered. All files before the error, will have been processed successfully. IMPORTANT! Please re-read the DISCLAIMER section at the beginning of this document BEFORE using this program. YOU USE THIS PROGRAM AT YOUR OWN RISK. If you think that your data is too important for even the SLIGHTEST possibility of data loss, DO NOT USE THIS PROGRAM! This program has been tested over the course of many months and has not caused any disk errors or data loss when following the guidelines mentioned above. This DOES NOT mean that data loss is impossible. If data loss occurs it is the responsibility of the user, NOT the author of the MultiRename program. In no event will the author be held liable for direct, indirect, incidental, or consequential damages resulting from the use or misuse of the program and information provided herein. PERFORMANCE AND DISK CACHING PROGRAMS When using MultiRename on files within a directory containing a few hundred files, the speed of the program is acceptable. When the program is used on a large directory of 1000 or more files, the speed can be slower than would be expected. This can be alleviated by the use of a disk caching program. The use of disk caching programs will GREATLY increase the performance of MultiRename. To see this performance increase you should turn off temporary directory creation since this was added to enhance the performance of non-disk caching systems and is unnecessary for disk caching systems. Sometimes the program will generate an error with the temporary directory structure turned off. If this occurs, just turn the directory structure back on by setting RENAMING METHOD to default. BUG REPORTS If you happen to find what you may think is a bug, please let me know. You may report a bug by Internet Email. My email address is: dan@chaos.mcs.mu.edu or milling@studsys.mscs.mu.edu CREDITS Programming and Manual Writing: Daniel S. Milling Jr. Compiled with: SAS C compiler Special Thanks To: John Woo - for making the best damn action films ever!